JSON-RPC 1.0

JSON-RPCの古い方

https://www.jsonrpc.org/specification_v1

比較用かなにかでGoogle翻訳してみる

JSON-RPC 1.0 仕様

仕様は、プロトコルの実装に必要な情報を開発者に提供するものです。

注記: JSON-RPC 2.0 仕様が公開されました。

概要

JSON-RPC は軽量なリモート・プロシージャ・コール・プロトコルです。シンプルさを追求して設計されています。

基本的なメカニズムは、2 つのピアがデータ接続を確立することで構成されます。接続が確立されている間、ピアは他方のピアが提供するメソッドを呼び出すことができます。リモートメソッドを呼び出すには、リクエストを送信します。リクエストが通知でない限り、レスポンスで応答する必要があります。

1.1 リクエスト (メソッド呼び出し)

リモートメソッドは、リモートサービスにリクエストを送信することで呼び出されます。リクエストは、JSON を使用してシリアル化された単一のオブジェクトです。

リクエストには 3 つのプロパティがあります。

method - 呼び出すメソッドの名前を含む文字列。

params - メソッドに引数として渡すオブジェクトの配列。

id - リクエスト ID。任意の型を指定できます。これは、応答と応答先のリクエストを照合するために使用されます。

1.2 レスポンス

メソッドの呼び出しが完了すると、サービスはレスポンスを返す必要があります。レスポンスは、JSON を使用してシリアル化された単一のオブジェクトです。

レスポンスには3つのプロパティがあります。

result - 呼び出されたメソッドによって返されたオブジェクト。メソッドの呼び出しでエラーが発生した場合は、null である必要があります。

error - メソッドの呼び出しでエラーが発生した場合は、Error オブジェクト。エラーがない場合は、null である必要があります。

id - 応答先のリクエストと同じ ID である必要があります。

1.3 通知

通知は、レスポンスを持たない特別なリクエストです。通知は、JSON を使用してシリアル化された単一のオブジェクトです。

通知は、1つの例外を除き、リクエストオブジェクトと同じプロパティを持ちます。

id - null である必要があります。

2.1 ストリーム接続を介した JSON-RPC

仕様では特定のトランスポートプロトコルは必須ではありません。TCP/IP ソケットストリームの使用が推奨されます。シリアル化されたリクエストオブジェクトとレスポンスオブジェクトは、バイトストリームを介してピアに送信されます。

リクエストとレスポンスは、いつでもピアに送信できます。ピアは、通知でない限り、すべてのリクエストに応答しなければなりません。レスポンスは、リクエストへの返信としてのみ送信できます。

ピア間の接続を閉じる際は、各ピアで応答がないすべてのリクエストに対して例外を発生させる必要があります。無効なリクエストまたはレスポンスは、接続を閉じる必要があります。

2.2 HTTP を介した JSON-RPC

いくつかの制限はありますが、HTTP リクエストはピア間の通信トランスポートとして使用できます。

一方が HTTP クライアント、もう一方が HTTP サーバーであるピア間の通信は、複数の HTTP リクエストにまたがる場合があります。クライアント側のピアは、すべてのシリアル化されたオブジェクトを含む HTTP POST リクエストを送信することで、1 つ以上のリクエスト、通知、またはレスポンスをピアに送信できます。

サーバー側ピアは、送信されたすべてのリクエストに対してレスポンスを返す必要があり、独自のリクエストや通知を送信することもできます。クライアント側ピアは、受信したリクエストに対して、別のHTTP POSTを送信してレスポンスを返す必要があります。

サーバー側ピアがクライアント側ピアにメッセージを送信する機会を与えるために、クライアント側ピアは空のHTTP POSTを送信することで通信を再開できます。

無効なリクエストは、接続を閉じる必要があります。無効なレスポンスは、クライアント側で応答されなかったすべてのリクエストに対して例外を発生させる必要があります。接続を閉じる場合は、クライアント側で応答されなかったすべてのリクエストに対して例外を発生させる必要があります。

FIXME: TCP接続では暗黙的にセッションが形成されることはないため、セッションの処理方法を説明/定義してください。

3. JSON クラスヒント

JSON では単純なデータ型のみが定義されています。この問題を JSON 互換の方法で解決するために、オブジェクト用の特別なプロパティが導入されています。

{"__jsonclass__":["constructor", param1,...], "prop1": ...}

オブジェクトは、パラメータを渡してコンストラクターでインスタンス化されます。構築されると、プロパティ (prop1, ...) が適用されます。

4. 通信例

--> サービスに送信されたデータ

<-- サービスから受信されたデータ

code:service.echo("Hello JSON-RPC")

--> { "method": "echo", "params": "Hello JSON-RPC", "id":

<-- { "result": "Hello JSON-RPC", "error": null, "id": 1}

複数のリクエスト応答

この例は、サンプルチャットアプリケーションの通信の一部を示しています。チャットサービスは、クライアントピアが受信する必要があるチャットメッセージごとに通知を送信します。クライアントピアは、チャットにメッセージを投稿するためのリクエストを送信し、メッセージが投稿されたことを知るための肯定応答を待ちます。

code:code

...

--> {"method": "postMessage", "params": "Hello all!", "id": 99}

<-- {"result": 1, "error": null, "id": 99}

<-- {"method": "handleMessage", "params": "user1", "we were just talking", "id":

null}

<-- {"method": "handleMessage", "params": "user3", "sorry, gotta go now, ttyl", "id":

null}

--> {"method": "postMessage", "params": "I have a question:", "id": 101}

<-- {"method": "userLeft", "params": "user3", "id": null}

<-- {"result": 1, "error": null, "id": 101}

...

本文書およびその翻訳は、JSON-RPCの実装に使用でき、複製および他者に提供できます。また、本文書についてコメント、説明、または実装を支援する派生著作物は、上記の著作権表示および本項をすべての複製および派生著作物に含めることを条件として、全体または一部を問わず、いかなる制限も受けることなく作成、複製、公開、配布できます。ただし、本文書自体はいかなる形でも改変できません。

上記で付与された限定的な権限は永続的であり、JSON-RPC.orgによって取り消されることはありません。

この文書およびここに含まれる情報は「現状有姿」で提供され、json-rpc.org は、ここに含まれる情報の使用がいかなる権利も侵害しないという保証、または商品性や特定目的への適合性に関する暗黙の保証を含むがこれに限定されない、明示的または黙示的なすべての保証を否認します。